Description

Completes the full migration from Clerk to Better Auth by removing every remaining Clerk reference across the codebase. Better Auth was already fully operational; this PR removes the dead/legacy Clerk layer.

Changes

Database (highest priority)

• migrations/0009_remove_clerk_fields.sql — New D1 migration that drops clerk_user_id from users and agent_sessions via SQLite table-recreation pattern. Removes the idx_users_clerk_user_id and idx_agent_sessions_clerk_user_id indexes. Migration follows the established pattern from 0004_users_email_nullable.sql: wrapped in PRAGMA foreign_keys = OFF/ON, temp tables use underscore-prefixed names (_users_new, _agent_sessions_new) without IF NOT EXISTS so partial runs fail loudly, and all pre-existing indexes are recreated (including idx_users_tier).
• prisma/schema.prisma — Removed clerkUserId String? @map("clerk_user_id") from the User model along with its legacy comment block.
• prisma/schema.d1.prisma — Removed clerkUserId @unique @map("clerk_user_id") from D1 User model; updated section header from // Users — synced from Clerk webhooks to // Users.
• prisma/generated/ + prisma/generated-d1/ — Regenerated both Prisma clients (deno task db:generate).

Storage schema fix (surfaced by Prisma regen)

The Neon migration 20260413000000_remove_clerk_fields had already dropped the token_hash column from the sessions table, but the generated Prisma types were stale and CreateSessionSchema / HyperdriveStorageAdapter.createSession() still referenced tokenHash. Regenerating the client surfaced this mismatch:

• src/storage/schemas.ts — Removed tokenHash from CreateSessionSchema.
• src/storage/HyperdriveStorageAdapter.ts — Removed tokenHash from prisma.session.create() call.
• src/storage/schemas.test.ts + HyperdriveStorageAdapter.test.ts — Updated tests accordingly.

Dead code deletion

• worker/services/user-service.ts — Deleted entirely. Contained ClerkUserData, upsertUserFromClerk, deleteUserByClerkId, findUserByClerkId, updateUserTier — all Clerk-only, never imported in production routing.
• worker/services/user-service.test.ts — Deleted (tested only the above dead code).

Worker cleanup

• worker/handlers/admin-handlers.ts — Removed clerk_user_id backward-compat fallback from the role-assignments list query param (?user_id= is the only accepted param now).
• Worker service JSDoc comments updated in admin-analytics-events.ts, admin-logger.ts, admin-audit-service.ts, admin-feature-flag-service.ts, admin-config-service.ts, feature-flag-service.ts.

Config

• .dev.vars.example — Removed the entire Clerk section: CLERK_PUBLISHABLE_KEY, CLERK_JWKS_URL, CLERK_SECRET_KEY, CLERK_WEBHOOK_SECRET, DISABLE_CLERK_FALLBACK, DISABLE_CLERK_WEBHOOKS.

Frontend

• admin/api-keys/api-keys.component.ts — Removed clerkUserId from the AdminApiKey interface, displayedColumns, filter logic, table column definition, and detail panel (the field was never returned by the worker API). Updated search label/placeholder from "Search by prefix or owner" → "Search by prefix or name" to accurately reflect the active filter fields (keyPrefix, name).
• admin/api-keys/api-keys.component.spec.ts — Removed clerkUserId from interface, factory, fixtures, and the stale 'filters by clerkUserId substring' test.
• admin/roles/roles.component.ts — Changed <mat-label>Clerk User ID</mat-label> → <mat-label>User ID</mat-label>.
• admin/roles/roles.component.spec.ts — Replaced 'clerk-abc', 'clerk-xyz', 'clerk-del' test fixture strings with neutral 'user-abc', 'user-xyz', 'user-del'.
• Stale comments updated in admin.guard.ts, app.routes.server.ts, api-key.service.ts, agent-rpc.service.ts, agent.models.ts, webhooks.component.ts, app.config.ts, components/api-keys/api-keys.component.spec.ts.

src/ library

• Stale "Clerk JWT bearer token" descriptions updated in IDiagnosticsProvider.ts, CliApp.deno.ts, ArgumentParser.ts, configuration/schemas.ts.

Scripts / Postman

• scripts/diag-full.ts — Removed the /api/clerk-config diagnostic probe (endpoint no longer exists).
• scripts/generate-postman-collection.ts — Renamed clerkToken → bearerToken collection variable.
• postman/environments/adblock-compiler.environment.yaml + adblock-compiler-local.environment.yaml — Renamed clerkJwt → bearerToken; removed clerkPublishableKey entries.

OpenAPI / generated API specs

• docs/api/openapi.yaml — Removed /api/webhooks/clerk path block, ClerkJWT security scheme, updated enum: [local-jwt, clerk] → [local-jwt, better-auth], updated endpoint descriptions.
• docs/api/cloudflare-schema.yaml and docs/postman/postman-collection.json — Regenerated via deno task schema:generate.

CI fix

• .github/workflows/neon-branch-create.yml — Replaced pnpm/action-setup@v6.0.0 (which caused ERR_PNPM_BROKEN_LOCKFILE in the Neon Branch: Create workflow) with the ./.github/actions/setup-pnpm-node composite action — the same SHA-pinned pnpm/action-setup@fc06bc1... # v4 used by all other CI jobs. Also upgraded the Node.js version from 20 → 22 to match the rest of CI.

Testing

• Unit tests added/updated
• Manual testing performed
• CI passes

deno task preflight exits 0 (fmt, lint, type-check, openapi:validate, schema:generate, check:drift all pass). deno task test — 1407 passed, 0 failed. Parallel validation (Code Review + CodeQL) — no issues found.

Zero Trust Architecture Checklist

Required for every PR touching worker/ or frontend/.
Check each item that applies. If an item doesn't apply, check it and note "N/A".

Worker / Backend

• Every handler verifies auth before executing business logic
• CORS origin allowlist enforced (not *) on write/authenticated endpoints
• All secrets accessed via Worker Secret bindings (not [vars]) — Clerk secret bindings removed from .dev.vars.example
• All external inputs Zod-validated before use
• All D1 queries use parameterized .prepare().bind() (no string interpolation)
• Security events emitted to Analytics Engine on auth failures

Frontend / Angular

• Protected routes have functional CanActivateFn auth guards
• Auth tokens managed via Clerk SDK (not localStorage) — N/A; Clerk SDK fully removed
• HTTP interceptor attaches ****** (no manual token passing)
• API responses validated with Zod schemas before consumption

API Shield / Vulnerability Scanner

Required for every PR touching docs/api/openapi.yaml, worker/routes/, or resource endpoint handlers.

• New/changed endpoints have a unique operationId in openapi.yaml
• Resource endpoints (those with /{id} path parameters) include a security: annotation
• Resource queries are scoped to the authenticated user (WHERE user_id = ?) — not just by ID
• Missing/unauthorized resources return 404 (not 403) to avoid leaking resource existence
• cloudflare-schema.yaml regenerated if openapi.yaml changed (deno task schema:cloudflare)